package com.docmgmt.mvp.ragflow.dto;

import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * 对话会话详情 VO
 * 
 * 用于接收 RAGFlow 的会话管理接口返回结果。
 * 
 * 对应的 RAGFlow API：
 * - POST /api/v1/chats/{chat_id}/sessions - 创建会话
 * - GET /api/v1/chats/{chat_id}/sessions - 列出会话
 * - GET /api/v1/chats/{chat_id}/sessions/{session_id} - 获取会话详情
 * 
 * 使用示例：
 * <pre>
 * SessionVO session = ragflowClient.createSession(chatId, request);
 * System.out.println("会话 ID：" + session.getId());
 * System.out.println("会话名称：" + session.getName());
 * System.out.println("创建时间：" + session.getCreateTime());
 * </pre>
 * 
 * @author Dora
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class SessionVO {

    /**
     * 会话 ID
     * 
     * RAGFlow 中会话的唯一标识符。
     * 
     * 格式：32 位十六进制字符串
     * 示例：session_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
     * 
     * 用途：
     * - 发送消息时指定会话 ID，实现多轮对话
     * - 查询会话的对话历史
     * - 更新会话名称
     * - 删除会话
     * 
     * 注意：
     * - 会话 ID 在创建后不可修改
     * - 会话 ID 必须属于指定的 Chat Assistant
     * - 删除会话后，ID 不可复用
     */
    private String id;

    /**
     * 会话名称
     * 
     * 用于标识和区分不同的对话会话。
     * 
     * 特点：
     * - 可以重复（系统通过 ID 区分）
     * - 可以修改
     * - 如果创建时未指定，系统自动生成默认名称
     * 
     * 示例：
     * - "讨论 RAGFlow 架构"
     * - "产品需求分析 - 2025-01-15"
     * - "会话 1"（系统自动生成）
     */
    private String name;

    /**
     * 所属 Chat Assistant ID
     * 
     * 标识该会话属于哪个 Chat Assistant。
     * 
     * 格式：32 位十六进制字符串
     * 示例：chat_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
     * 
     * 用途：
     * - 验证会话归属
     * - 查询 Chat Assistant 的所有会话
     * - 权限控制（用户是否有权访问该会话）
     * 
     * 注意：
     * - 会话创建后，chat_id 不可修改
     * - 删除 Chat Assistant 会同时删除其所有会话
     */
    @JsonProperty("chat_id")
    private String chatId;

    /**
     * 创建时间
     * 
     * 会话的创建时间戳。
     * 
     * 格式：ISO 8601 格式或自定义格式
     * 示例：
     * - "2025-01-15T10:30:00Z"（ISO 8601）
     * - "2025-01-15 10:30:00"（自定义格式）
     * 
     * 用途：
     * - 按时间排序会话列表
     * - 显示会话的创建日期
     * - 统计会话的使用时长
     */
    @JsonProperty("create_time")
    private String createTime;

    /**
     * 更新时间
     * 
     * 会话的最后更新时间戳。
     * 
     * 更新时机：
     * - 修改会话名称
     * - 发送新消息
     * - 删除消息
     * 
     * 格式：同 create_time
     * 
     * 用途：
     * - 按活跃度排序会话列表
     * - 显示会话的最后活动时间
     * - 实现"最近使用"功能
     * 
     * 注意：
     * - 如果会话从未更新，update_time 可能等于 create_time
     * - 某些操作（如查询历史）不会更新此字段
     */
    @JsonProperty("update_time")
    private String updateTime;

    /**
     * 消息数量（可选字段）
     * 
     * 该会话包含的消息总数（用户消息 + AI 回复）。
     * 
     * 用途：
     * - 显示会话的活跃度
     * - 判断会话是否为空
     * - 统计对话轮数（message_count / 2）
     * 
     * 注意：
     * - 此字段可能不在所有 API 返回中出现
     * - 如果为 null，需要通过查询消息历史获取
     */
    @JsonProperty("message_count")
    private Integer messageCount;

    /**
     * 最后一条消息内容（可选字段）
     * 
     * 该会话的最后一条消息的内容摘要。
     * 
     * 用途：
     * - 在会话列表中显示预览
     * - 帮助用户快速识别会话内容
     * 
     * 特点：
     * - 可能被截断（如只显示前 100 个字符）
     * - 可能为用户消息或 AI 回复
     * 
     * 注意：
     * - 此字段可能不在所有 API 返回中出现
     * - 如果会话为空，此字段为 null
     */
    @JsonProperty("last_message")
    private String lastMessage;

    // ==================== 辅助方法 ====================

    /**
     * 判断会话是否为空（没有消息）
     * 
     * @return 是否为空会话
     */
    public boolean isEmpty() {
        return messageCount == null || messageCount == 0;
    }

    /**
     * 获取对话轮数
     * 
     * 对话轮数 = 消息总数 / 2（假设每轮包含一个用户消息和一个 AI 回复）
     * 
     * @return 对话轮数
     */
    public int getRoundCount() {
        return messageCount != null ? messageCount / 2 : 0;
    }

    /**
     * 获取会话名称（非空安全）
     * 
     * 如果 name 为 null 或空字符串，返回默认名称。
     * 
     * @return 会话名称
     */
    public String getNameOrDefault() {
        if (name == null || name.trim().isEmpty()) {
            return "未命名会话";
        }
        return name;
    }
}

